Do you hate it when you open a piece of script and there are no comments? There is something comforting about seeing some lines of green text when you are up to your neck in a problem. Knowing that someone, probably the person that wrote the script was thinking about you and your predicament, even though they are not around nor have any idea why you are looking at their code.

Several years ago I was managing a young developer who had grown up coding at home, making his own websites and generally being a bit of a whizz kid. In my role I was managing his administration and development of our customer facing website and our internal web services. The problem came when he was on holiday, I might pick up a problem and not have a clue what his code was doing; include files, javascript, vbscript, innerhtml this, marquee tag that . I was lost because there was no commenting. Anywhere.

This happened a few times, each holiday was followed by a email from me whining about how I couldn’t just pick up on his techniques and patterns without some guide as to the code’s intention in comments. Nothing happened.

After a particular time I added comments to the code to explain to myself what I thought was going on and had a minor rant too. My sarcastic side let rip. When he came back to work he happened across the code a few days later and started laughing. Some time later I found some of his code with comments about how he was explaining what was going on to stop me adding sarcastic comments. Then it spread, film quotes, punchlines from comedy shows were appearing all over the place, along with actual code explaining comments. It had taken hold, supporting his code became simple and fun.

Whether he was treating it like graffiti and ‘tagging’ his code or some other reason I dont know, the result though was code that brings back memories, is fun to support and makes our jobs more fun.

I know not all places allow for this style of coding and it carries risks if they get out of hand but in this case it worked well. What methods have you got or used to encourage commenting in your code?